This variable is an association list which maps syntactic symbols to lists of places to insert a newline. See Association Lists. The key of each element is the syntactic symbol, the associated value is either nil, a list, or a function.

The Key - the syntactic symbol

The syntactic symbols that are useful as keys in this list are brace-list-intro, statement-cont, inexpr-class-open, inexpr-class-close, and all the *-open and *-close symbols. See Syntactic Symbols, for a more detailed description of these syntactic symbols, except for inexpr-class-open and inexpr-class-close, which aren't actual syntactic symbols. Elements with any other value as a key get ignored.

The braces of anonymous inner classes in Java are given the special symbols inexpr-class-open and inexpr-class-close, so that they can be distinguished from the braces of normal classes².

Note that the aggregate constructs in Pike mode, ‘({’, ‘})’, ‘([’, ‘])’, and ‘(<’, ‘>)’, do not count as brace lists in this regard, even though they do for normal indentation purposes. It's currently not possible to set automatic newlines on these constructs.

The associated value - the “ACTION” list or function

The value associated with each syntactic symbol in this association list is called an action, which can be either a list or a function which returns a list. See Custom Braces, for how to use a function as a brace hanging action.

The list action (or the list returned by action when it's a function) contains some combination of the symbols before and after, directing CC Mode where to put newlines in relationship to the brace being inserted. Thus, if the list contains only the symbol after, then the brace hangs on the right side of the line, as in:

               // here, open braces always `hang'
               void spam( int i ) {
                   if( i == 7 ) {
                       dosomething(i);
                   }
               }

When the list contains both after and before, the braces will appear on a line by themselves, as shown by the close braces in the above example. The list can also be empty, in which case newlines are added neither before nor after the brace.

If a syntactic symbol is missing entirely from c-hanging-braces-alist, it's treated in the same way as an action with a list containing before and after, so that braces by default end up on their own line.

For example, the default value of c-hanging-braces-alist is:

          ((brace-list-open)
           (brace-entry-open)
           (statement-cont)
           (substatement-open after)
           (block-close . c-snug-do-while)
           (extern-lang-open after)
           (namespace-open after)
           (module-open after)
           (composition-open after)
           (inexpr-class-open after)
           (inexpr-class-close before))

which says that brace-list-open, brace-entry-open and statement-cont³ braces should both hang on the right side and allow subsequent text to follow on the same line as the brace. Also, substatement-open, extern-lang-open, and inexpr-class-open braces should hang on the right side, but subsequent text should follow on the next line. The opposite holds for inexpr-class-close braces; they won't hang, but the following text continues on the same line. Here, in the block-close entry, you also see an example of using a function as an action. In all other cases, braces are put on a line by themselves.